Keep DB content out of the coordination repo + resite runbook

.claude/hooks/block-db-writes.sh

@@ -0,0 +1,71 @@
+#!/bin/sh
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# block-db-writes.sh — Claude Code PreToolUse hook for nextgen-databases.
+#
+# nextgen-databases is a COORDINATION repo. Per-database code/docs belong in each
+# database's own repo (see REGISTRY.adoc). This hook blocks creation of a NEW file
+# inside a legacy per-database directory (that is the misplacement we are stopping),
+# while still allowing edits to files that already exist during the transition.
+#
+# Reads the hook payload (JSON) on stdin. Exit 2 = BLOCK (reason on stderr); 0 = ALLOW.
+
+set -u
+
+payload="$(cat)"
+root="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+# --- extract a leaf value from the JSON payload ------------------------------
+extract() { # $1 = jq path, e.g. .tool_input.file_path
+  if command -v jq >/dev/null 2>&1; then
+    printf '%s' "$payload" | jq -r "$1 // empty" 2>/dev/null
+  else
+    leaf="${1##*.}"
+    printf '%s' "$payload" | tr ',{}' '\n\n\n' \
+      | sed -n "s/.*\"${leaf}\"[[:space:]]*:[[:space:]]*\"\([^\"]*\)\".*/\1/p" | head -n1
+  fi
+}
+
+tool="$(extract .tool_name)"
+fp="$(extract .tool_input.file_path)"
+
+# Only police file-writing tools.
+case "$tool" in
+  Write|Edit|MultiEdit|NotebookEdit) ;;
+  *) exit 0 ;;
+esac
+
+[ -n "$fp" ] || exit 0
+
+# Normalise to a repo-relative path.
+rel="$fp"
+case "$fp" in
+  "$root"/*) rel="${fp#"$root"/}" ;;
+  /*) exit 0 ;;            # absolute path outside the project — not ours to police
+esac
+
+# Map a legacy database directory to its destination repo (for a helpful message).
+dest=""
+case "$rel" in
+  verisimdb/*)                  dest="hyperpolymath/verisimdb" ;;
+  lithoglyph/glyphbase/*)       dest="hyperpolymath/glyphbase" ;;
+  lithoglyph/gql-dt/*)          dest="hyperpolymath/gnpl" ;;
+  lithoglyph/*)                 dest="hyperpolymath/lithoglyph" ;;
+  quandledb/*)                  dest="hyperpolymath/quandledb" ;;
+  nqc/*)                        dest="hyperpolymath/nqc" ;;
+  typeql-experimental/*)        dest="hyperpolymath/vcl-ut" ;;
+  verisim-core/*)               dest="hyperpolymath/verisim-core (or fold into verisimdb)" ;;
+  verisim-modular-experiment/*) dest="" ;;   # research-only — allowed for now
+esac
+
+# Block creation of a NEW file in a database directory; allow edits to existing files.
+if [ -n "$dest" ] && [ ! -e "$fp" ]; then
+  printf '%s\n' "BLOCKED: nextgen-databases is a COORDINATION repo — do not add new per-database content here." 1>&2
+  printf '%s\n' "  New file:        $rel" 1>&2
+  printf '%s\n' "  This belongs in: $dest  (see REGISTRY.adoc)" 1>&2
+  printf '%s\n' "  If this really is coordination content, place it outside the database directories." 1>&2
+  exit 2
+fi
+
+exit 0

.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/block-db-writes.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

.github/workflows/placement-guard.yml

@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# placement-guard.yml — Coordination-repo content placement guard.
+# nextgen-databases is a COORDINATION repo: per-database implementation content belongs
+# in each database's own repo (see REGISTRY.adoc), not here. This gate FAILS a PR/push
+# that ADDS files outside the allowed coordination paths.
+name: Placement Guard
+
+on:
+  pull_request:
+    branches: ['**']
+  push:
+    branches: [main, master]
+
+permissions:
+  contents: read
+
+jobs:
+  placement:
+    name: Content placement check
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          fetch-depth: 0
+
+      - name: Determine added files
+        id: diff
+        run: |
+          set -uo pipefail
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            git fetch --no-tags origin "${{ github.base_ref }}" || true
+            BASE="origin/${{ github.base_ref }}"
+          else
+            BASE="${{ github.event.before }}"
+            case "$BASE" in
+              0000000000000000000000000000000000000000|"") BASE="$(git rev-parse HEAD~1 2>/dev/null || echo origin/main)" ;;
+            esac
+          fi
+          echo "Comparing against: $BASE"
+          git diff --name-only --diff-filter=A "$BASE...HEAD" > /tmp/added.txt 2>/dev/null \
+            || git diff --name-only --diff-filter=A "$BASE" HEAD > /tmp/added.txt
+          echo "Added files:"; cat /tmp/added.txt || true
+
+      - name: Check placement
+        run: |
+          set -uo pipefail
+
+          # Allowed coordination paths (regex, anchored at repo root).
+          ALLOW='^(README|EXPLAINME|TOPOLOGY|ROADMAP|TOOLING-STATUS|REGISTRY|CONTRIBUTING|CODE_OF_CONDUCT|SECURITY|MAINTAINERS|NOTICE|LICENSE|PROOF-NEEDS|TEST-NEEDS|QUICKSTART-[A-Z]+|0-AI-MANIFEST|CLAUDE|AGENTS|llm-warmup-[a-z]+)\.[A-Za-z0-9]+$'
+          ALLOW="$ALLOW"'|^(docs|tests|scripts|\.github|\.claude|\.machine_readable|\.bot_directives|\.well-known|\.hypatia|LICENSES|contractiles)/'
+          ALLOW="$ALLOW"'|^(flake\.nix|guix\.scm|Justfile|contractile\.just|stapeln\.toml|opsm\.toml|setup\.sh|\.gitignore|\.gitattributes|\.editorconfig|\.gitlab-ci\.yml|\.nojekyll)$'
+
+          # Legacy per-database dirs (grandfathered: warn, do not fail — being extracted).
+          GRANDFATHER='^(verisimdb|lithoglyph|quandledb|nqc|typeql-experimental|verisim-core|verisim-modular-experiment)/'
+
+          FAIL=0
+          while IFS= read -r f; do
+            [ -z "$f" ] && continue
+            if echo "$f" | grep -Eq "$ALLOW"; then
+              continue
+            fi
+            if echo "$f" | grep -Eq "$GRANDFATHER"; then
+              echo "::warning file=${f}::Added inside a legacy database directory. This content should live in its own repo (see REGISTRY.adoc); these directories are being extracted."
+              continue
+            fi
+            echo "::error file=${f}::Misplaced content. nextgen-databases is a coordination repo — this belongs in a database/language repo. See REGISTRY.adoc."
+            FAIL=1
+          done < /tmp/added.txt
+
+          {
+            echo "## Placement Guard"
+            echo ""
+            if [ "$FAIL" -eq 0 ]; then
+              echo ":white_check_mark: No misplaced new content detected."
+            else
+              echo ":x: New files were added outside the allowed coordination paths."
+              echo ""
+              echo "\`nextgen-databases\` is a **coordination repo**. Per-database code, schemas,"
+              echo "docs, and query languages belong in their own repos — see \`REGISTRY.adoc\`."
+            fi
+          } >> "$GITHUB_STEP_SUMMARY"
+
+          exit $FAIL

.machine_readable/6a2/AGENTIC.a2ml

@@ -22,3 +22,6 @@ can-create-files = true
 # - Never use banned languages (TypeScript, Python, Go, etc.)
 # - Never place state files in repository root (must be in .machine_readable/)
 # - Never use AGPL license (use PMPL-1.0-or-later)
+# - Never add per-database implementation content (source, schemas, migrations,
+#   per-database docs, query-language implementations) to this COORDINATION repo;
+#   it belongs in that database's own repo (see REGISTRY.adoc)

0-AI-MANIFEST.a2ml

@@ -40,37 +40,43 @@ Bot-specific instructions for:
 
 ## CORE INVARIANTS
 
-1. **No SCM duplication** - Root must NOT contain .machine_readable/6a2/STATE.a2ml, .machine_readable/6a2/META.a2ml, 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 PMPL-1.0-or-later unless platform requires MPL-2.0
-5. **Author attribution** - Always "Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>"
+1. **Coordination only — no implementation** - This repo coordinates a portfolio of
+   databases. Per-database source, schemas, migrations, query-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 SCM duplication** - Root must NOT contain .machine_readable/6a2/STATE.a2ml, .machine_readable/6a2/META.a2ml, etc.
+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
 
-<!-- CUSTOMIZE THIS SECTION FOR YOUR REPO -->
-
-This repo contains:
+This is a **coordination repo**. Intended (target) contents:
 
 ```
 nextgen-databases/
-├── 0-AI-MANIFEST.a2ml         # THIS FILE (start here)
-├── README.adoc                 # Database portfolio overview
-├── .machine_readable/          # SCM files (6 files)
-│   ├── .machine_readable/6a2/STATE.a2ml
-│   ├── .machine_readable/6a2/META.a2ml
-│   ├── .machine_readable/6a2/ECOSYSTEM.a2ml
-│   ├── .machine_readable/6a2/AGENTIC.a2ml
-│   ├── .machine_readable/6a2/NEUROSYM.a2ml
-│   └── .machine_readable/6a2/PLAYBOOK.a2ml
-├── .bot_directives/            # Bot instructions
-└── contractiles/               # Contractiles
+├── 0-AI-MANIFEST.a2ml          # THIS FILE (start here)
+├── CLAUDE.md / AGENTS.md       # Agent guardrails (coordination-only)
+├── REGISTRY.adoc               # Authoritative map: database/language -> its own repo
+├── README.adoc / EXPLAINME.adoc / TOPOLOGY.md / 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 repository** — no implementation code.
-Satellite repos: quandledb, verisimdb, lithoglyph, glyphbase
+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, nqc.
 
 ## SESSION STARTUP CHECKLIST
 

AGENTS.md

@@ -0,0 +1,13 @@
+<!-- SPDX-License-Identifier: MPL-2.0 -->
+# AGENTS.md
+
+This is the **nextgen-databases coordination repo** — it does **not** hold database
+implementations. Per-database code, schemas, docs, and query languages each live in
+their **own repo** (see `REGISTRY.adoc`).
+
+**Do not add per-database implementation content here.** If you are about to add database
+source, schemas, migrations, a query-language implementation, or per-database docs, it
+belongs in that database's own repo — not here.
+
+Full guidance: **`CLAUDE.md`** (same directory). Universal AI entry point:
+**`0-AI-MANIFEST.a2ml`**. Authoritative repo map: **`REGISTRY.adoc`**.

CLAUDE.md

@@ -0,0 +1,52 @@
+<!-- SPDX-License-Identifier: MPL-2.0 -->
+# CLAUDE.md — nextgen-databases (COORDINATION REPO)
+
+## CRITICAL: This is a coordination repo. No database implementation lives here. (Read First)
+
+`nextgen-databases` **coordinates** a portfolio of database projects. It does **not**
+hold their implementations. Each database and each query language has its **own repo**
+(see `REGISTRY.adoc`).
+
+**Before you create or edit a file here, STOP and ask: is this coordination, or is it
+about one specific database?** If it is about one database, it belongs in that database's
+own repo.
+
+### NEVER (in this repo)
+
+1. **NEVER** add per-database source code, schemas, migrations, storage engines, or
+   query-language implementations here.
+2. **NEVER** add per-database design docs, whitepapers, benchmarks, or datasets here.
+3. **NEVER** create a new top-level directory for a database or language — create or
+   extend its own repo instead (`REGISTRY.adoc`).
+4. **NEVER** "just put it here for now." That is exactly the drift this repo is
+   recovering from.
+
+### ALWAYS (what DOES belong here)
+
+1. **Portfolio coordination**: `README.adoc`, `TOPOLOGY.md`, `ROADMAP.adoc`,
+   `EXPLAINME.adoc`.
+2. **The registry** of databases/languages → their repos: `REGISTRY.adoc`.
+3. **Cross-database** integration tests (`tests/`) and shared infrastructure
+   (`flake.nix`, `Justfile`, `stapeln.toml`, `opsm.toml`).
+4. **Governance & metadata**: `.github/`, `.machine_readable/`, `.well-known/`,
+   `LICENSES/`, `CONTRIBUTING.md`, `SECURITY.md`, `0-AI-MANIFEST.a2ml`.
+
+### Where database content goes
+
+See **`REGISTRY.adoc`** for the authoritative map. Examples: VeriSimDB →
+`hyperpolymath/verisimdb`; Lithoglyph → `hyperpolymath/lithoglyph`; Glyphbase →
+`hyperpolymath/glyphbase`; the Glyph query language → `hyperpolymath/gnpl`; NQC →
+`hyperpolymath/nqc`.
+
+### Transitional note
+
+The directories `verisimdb/`, `lithoglyph/`, `quandledb/`, `nqc/`,
+`typeql-experimental/`, `verisim-core/`, and `verisim-modular-experiment/` are **legacy
+content being extracted** to their own repos — see
+`docs/migration/RESITE-DATABASES-TO-OWN-REPOS.adoc`. **Do not grow them.** A CI guard
+(`.github/workflows/placement-guard.yml`) and a local pre-write hook
+(`.claude/hooks/block-db-writes.sh`) enforce this: creating a *new* file inside those
+directories is blocked, because it belongs in that database's own repo.
+
+---
+*Also read `0-AI-MANIFEST.a2ml` (universal AI entry point) and `AGENTS.md`.*

CONTRIBUTING.md

@@ -16,35 +16,34 @@ just test    # Run test suite
 ```
 
 ### Repository Structure
+
+`nextgen-databases` is a **coordination repo** — it does not hold database
+implementations. Each database and query language has its own repo (see `REGISTRY.adoc`).
+
 ```
 nextgen-databases/
-├── src/                 # Source code (Perimeter 1-2)
-├── lib/                 # Library code (Perimeter 1-2)
-├── extensions/          # Extensions (Perimeter 2)
-├── plugins/             # Plugins (Perimeter 2)
-├── tools/               # Tooling (Perimeter 2)
-├── docs/                # Documentation (Perimeter 3)
-│   ├── architecture/    # ADRs, specs (Perimeter 2)
-│   └── proposals/       # RFCs (Perimeter 3)
-├── examples/            # Examples (Perimeter 3)
-├── spec/                # Spec tests (Perimeter 3)
-├── tests/               # Test suite (Perimeter 2-3)
-├── .well-known/         # Protocol files (Perimeter 1-3)
-├── .github/             # GitHub config (Perimeter 1)
-│   ├── ISSUE_TEMPLATE/
-│   └── workflows/
-├── CHANGELOG.md
-├── CODE_OF_CONDUCT.md
-├── CONTRIBUTING.md      # This file
-├── GOVERNANCE.md
-├── LICENSE
-├── MAINTAINERS.md
-├── README.adoc
-├── SECURITY.md
-├── flake.nix            # Nix flake (Perimeter 1)
-└── Justfile             # Task runner (Perimeter 1)
+├── README.adoc / EXPLAINME.adoc / TOPOLOGY.md / ROADMAP.adoc  # Portfolio docs
+├── REGISTRY.adoc        # Authoritative map: database/language -> its own repo
+├── CLAUDE.md / AGENTS.md / 0-AI-MANIFEST.a2ml                 # Agent guardrails
+├── docs/                # Coordination docs (incl. migration runbooks)
+├── tests/               # CROSS-database integration tests only
+├── .machine_readable/   # Canonical SCM metadata
+├── .github/             # CI/CD, issue templates, governance
+├── .well-known/ LICENSES/
+└── flake.nix / Justfile / stapeln.toml / opsm.toml           # Shared env & orchestration
 ```
 
+#### What belongs here vs. in a database repo
+
+- ✅ **Here**: portfolio docs, the registry, cross-database integration tests, shared
+  infrastructure/orchestration, governance and machine-readable metadata.
+- ❌ **Not here — use the database's own repo**: per-database source code, schemas,
+  migrations, storage engines, query-language implementations, per-database design docs,
+  whitepapers, benchmarks, and datasets. See `REGISTRY.adoc` for the destination repo.
+
+A CI guard (`.github/workflows/placement-guard.yml`) and a local pre-write hook
+(`.claude/hooks/block-db-writes.sh`) enforce this.
+
 ---
 
 ## How to Contribute