Skip to content

Commit 1fd00b8

Browse files
claudeclaude
committed
chore(coordination): guard against misplaced DB content + resite runbook
nextgen-databases documents itself as a thin coordination repo ("no implementation code lives here") but physically holds full database implementations, and there was no top-level guardrail — so LLMs keep adding per-database content here instead of in each database's own repo. Prevention (stops the drift): - Root CLAUDE.md / AGENTS.md: coordination-only instructions - REGISTRY.adoc: authoritative database/language -> repo map - 0-AI-MANIFEST.a2ml + AGENTIC.a2ml: new "coordination only" invariant/constraint - CONTRIBUTING.md: accurate structure + what belongs here vs a database repo - .github/workflows/placement-guard.yml: fails PRs that add misplaced files - .claude/ pre-write hook: blocks new per-database files locally Remediation (resite, executed later): - docs/migration/RESITE-DATABASES-TO-OWN-REPOS.adoc: history-preserving extraction runbook + mapping + open decisions - scripts/resite/extract-subdir.sh: helper (does not push) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01W8DXRHQRBgxwSdDz8om287
1 parent 1913dde commit 1fd00b8

11 files changed

Lines changed: 509 additions & 46 deletions

File tree

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

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
#!/bin/sh
2+
# SPDX-License-Identifier: MPL-2.0
3+
# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
4+
#
5+
# block-db-writes.sh — Claude Code PreToolUse hook for nextgen-databases.
6+
#
7+
# nextgen-databases is a COORDINATION repo. Per-database code/docs belong in each
8+
# database's own repo (see REGISTRY.adoc). This hook blocks creation of a NEW file
9+
# inside a legacy per-database directory (that is the misplacement we are stopping),
10+
# while still allowing edits to files that already exist during the transition.
11+
#
12+
# Reads the hook payload (JSON) on stdin. Exit 2 = BLOCK (reason on stderr); 0 = ALLOW.
13+
14+
set -u
15+
16+
payload="$(cat)"
17+
root="${CLAUDE_PROJECT_DIR:-$(pwd)}"
18+
19+
# --- extract a leaf value from the JSON payload ------------------------------
20+
extract() { # $1 = jq path, e.g. .tool_input.file_path
21+
if command -v jq >/dev/null 2>&1; then
22+
printf '%s' "$payload" | jq -r "$1 // empty" 2>/dev/null
23+
else
24+
leaf="${1##*.}"
25+
printf '%s' "$payload" | tr ',{}' '\n\n\n' \
26+
| sed -n "s/.*\"${leaf}\"[[:space:]]*:[[:space:]]*\"\([^\"]*\)\".*/\1/p" | head -n1
27+
fi
28+
}
29+
30+
tool="$(extract .tool_name)"
31+
fp="$(extract .tool_input.file_path)"
32+
33+
# Only police file-writing tools.
34+
case "$tool" in
35+
Write|Edit|MultiEdit|NotebookEdit) ;;
36+
*) exit 0 ;;
37+
esac
38+
39+
[ -n "$fp" ] || exit 0
40+
41+
# Normalise to a repo-relative path.
42+
rel="$fp"
43+
case "$fp" in
44+
"$root"/*) rel="${fp#"$root"/}" ;;
45+
/*) exit 0 ;; # absolute path outside the project — not ours to police
46+
esac
47+
48+
# Map a legacy database directory to its destination repo (for a helpful message).
49+
dest=""
50+
case "$rel" in
51+
verisimdb/*) dest="hyperpolymath/verisimdb" ;;
52+
lithoglyph/glyphbase/*) dest="hyperpolymath/glyphbase" ;;
53+
lithoglyph/gql-dt/*) dest="hyperpolymath/gnpl" ;;
54+
lithoglyph/*) dest="hyperpolymath/lithoglyph" ;;
55+
quandledb/*) dest="hyperpolymath/quandledb" ;;
56+
nqc/*) dest="hyperpolymath/nqc" ;;
57+
typeql-experimental/*) dest="hyperpolymath/vcl-ut" ;;
58+
verisim-core/*) dest="hyperpolymath/verisim-core (or fold into verisimdb)" ;;
59+
verisim-modular-experiment/*) dest="" ;; # research-only — allowed for now
60+
esac
61+
62+
# Block creation of a NEW file in a database directory; allow edits to existing files.
63+
if [ -n "$dest" ] && [ ! -e "$fp" ]; then
64+
printf '%s\n' "BLOCKED: nextgen-databases is a COORDINATION repo — do not add new per-database content here." 1>&2
65+
printf '%s\n' " New file: $rel" 1>&2
66+
printf '%s\n' " This belongs in: $dest (see REGISTRY.adoc)" 1>&2
67+
printf '%s\n' " If this really is coordination content, place it outside the database directories." 1>&2
68+
exit 2
69+
fi
70+
71+
exit 0

‎.claude/settings.json‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"hooks": {
3+
"PreToolUse": [
4+
{
5+
"matcher": "Write|Edit|MultiEdit|NotebookEdit",
6+
"hooks": [
7+
{
8+
"type": "command",
9+
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/block-db-writes.sh"
10+
}
11+
]
12+
}
13+
]
14+
}
15+
}

‎.github/workflows/placement-guard.yml‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# SPDX-License-Identifier: MPL-2.0
2+
# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
3+
#
4+
# placement-guard.yml — Coordination-repo content placement guard.
5+
# nextgen-databases is a COORDINATION repo: per-database implementation content belongs
6+
# in each database's own repo (see REGISTRY.adoc), not here. This gate FAILS a PR/push
7+
# that ADDS files outside the allowed coordination paths.
8+
name: Placement Guard
9+
10+
on:
11+
pull_request:
12+
branches: ['**']
13+
push:
14+
branches: [main, master]
15+
16+
permissions:
17+
contents: read
18+
19+
jobs:
20+
placement:
21+
name: Content placement check
22+
runs-on: ubuntu-latest
23+
24+
steps:
25+
- name: Checkout repository
26+
uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
27+
with:
28+
fetch-depth: 0
29+
30+
- name: Determine added files
31+
id: diff
32+
run: |
33+
set -uo pipefail
34+
if [ "${{ github.event_name }}" = "pull_request" ]; then
35+
git fetch --no-tags origin "${{ github.base_ref }}" || true
36+
BASE="origin/${{ github.base_ref }}"
37+
else
38+
BASE="${{ github.event.before }}"
39+
case "$BASE" in
40+
0000000000000000000000000000000000000000|"") BASE="$(git rev-parse HEAD~1 2>/dev/null || echo origin/main)" ;;
41+
esac
42+
fi
43+
echo "Comparing against: $BASE"
44+
git diff --name-only --diff-filter=A "$BASE...HEAD" > /tmp/added.txt 2>/dev/null \
45+
|| git diff --name-only --diff-filter=A "$BASE" HEAD > /tmp/added.txt
46+
echo "Added files:"; cat /tmp/added.txt || true
47+
48+
- name: Check placement
49+
run: |
50+
set -uo pipefail
51+
52+
# Allowed coordination paths (regex, anchored at repo root).
53+
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]+$'
54+
ALLOW="$ALLOW"'|^(docs|tests|scripts|\.github|\.claude|\.machine_readable|\.bot_directives|\.well-known|\.hypatia|LICENSES|contractiles)/'
55+
ALLOW="$ALLOW"'|^(flake\.nix|guix\.scm|Justfile|contractile\.just|stapeln\.toml|opsm\.toml|setup\.sh|\.gitignore|\.gitattributes|\.editorconfig|\.gitlab-ci\.yml|\.nojekyll)$'
56+
57+
# Legacy per-database dirs (grandfathered: warn, do not fail — being extracted).
58+
GRANDFATHER='^(verisimdb|lithoglyph|quandledb|nqc|typeql-experimental|verisim-core|verisim-modular-experiment)/'
59+
60+
FAIL=0
61+
while IFS= read -r f; do
62+
[ -z "$f" ] && continue
63+
if echo "$f" | grep -Eq "$ALLOW"; then
64+
continue
65+
fi
66+
if echo "$f" | grep -Eq "$GRANDFATHER"; then
67+
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."
68+
continue
69+
fi
70+
echo "::error file=${f}::Misplaced content. nextgen-databases is a coordination repo — this belongs in a database/language repo. See REGISTRY.adoc."
71+
FAIL=1
72+
done < /tmp/added.txt
73+
74+
{
75+
echo "## Placement Guard"
76+
echo ""
77+
if [ "$FAIL" -eq 0 ]; then
78+
echo ":white_check_mark: No misplaced new content detected."
79+
else
80+
echo ":x: New files were added outside the allowed coordination paths."
81+
echo ""
82+
echo "\`nextgen-databases\` is a **coordination repo**. Per-database code, schemas,"
83+
echo "docs, and query languages belong in their own repos — see \`REGISTRY.adoc\`."
84+
fi
85+
} >> "$GITHUB_STEP_SUMMARY"
86+
87+
exit $FAIL

‎.machine_readable/6a2/AGENTIC.a2ml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,3 +22,6 @@ can-create-files = true
2222
# - Never use banned languages (TypeScript, Python, Go, etc.)
2323
# - Never place state files in repository root (must be in .machine_readable/)
2424
# - Never use AGPL license (use PMPL-1.0-or-later)
25+
# - Never add per-database implementation content (source, schemas, migrations,
26+
# per-database docs, query-language implementations) to this COORDINATION repo;
27+
# it belongs in that database's own repo (see REGISTRY.adoc)

‎0-AI-MANIFEST.a2ml‎

Lines changed: 27 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -40,37 +40,43 @@ Bot-specific instructions for:
4040

4141
## CORE INVARIANTS
4242

43-
1. **No SCM duplication** - Root must NOT contain .machine_readable/6a2/STATE.a2ml, .machine_readable/6a2/META.a2ml, etc.
44-
2. **Single source of truth** - `.machine_readable/` is authoritative
45-
3. **No stale metadata** - If root SCMs exist, they are OUT OF DATE
46-
4. **License consistency** - All code PMPL-1.0-or-later unless platform requires MPL-2.0
47-
5. **Author attribution** - Always "Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>"
43+
1. **Coordination only — no implementation** - This repo coordinates a portfolio of
44+
databases. Per-database source, schemas, migrations, query-language implementations,
45+
and per-database docs MUST live in that database's own repo (see `REGISTRY.adoc`).
46+
Adding per-database implementation content here is an ERROR.
47+
2. **No SCM duplication** - Root must NOT contain .machine_readable/6a2/STATE.a2ml, .machine_readable/6a2/META.a2ml, etc.
48+
3. **Single source of truth** - `.machine_readable/` is authoritative
49+
4. **No stale metadata** - If root SCMs exist, they are OUT OF DATE
50+
5. **License consistency** - All code PMPL-1.0-or-later unless platform requires MPL-2.0
51+
6. **Author attribution** - Always "Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>"
4852

4953
## REPOSITORY STRUCTURE
5054

51-
<!-- CUSTOMIZE THIS SECTION FOR YOUR REPO -->
52-
53-
This repo contains:
55+
This is a **coordination repo**. Intended (target) contents:
5456

5557
```
5658
nextgen-databases/
57-
├── 0-AI-MANIFEST.a2ml # THIS FILE (start here)
58-
├── README.adoc # Database portfolio overview
59-
├── .machine_readable/ # SCM files (6 files)
60-
│ ├── .machine_readable/6a2/STATE.a2ml
61-
│ ├── .machine_readable/6a2/META.a2ml
62-
│ ├── .machine_readable/6a2/ECOSYSTEM.a2ml
63-
│ ├── .machine_readable/6a2/AGENTIC.a2ml
64-
│ ├── .machine_readable/6a2/NEUROSYM.a2ml
65-
│ └── .machine_readable/6a2/PLAYBOOK.a2ml
66-
├── .bot_directives/ # Bot instructions
67-
└── contractiles/ # Contractiles
59+
├── 0-AI-MANIFEST.a2ml # THIS FILE (start here)
60+
├── CLAUDE.md / AGENTS.md # Agent guardrails (coordination-only)
61+
├── REGISTRY.adoc # Authoritative map: database/language -> its own repo
62+
├── README.adoc / EXPLAINME.adoc / TOPOLOGY.md / ROADMAP.adoc # Portfolio docs
63+
├── tests/ # CROSS-database integration tests only
64+
├── docs/ # Coordination docs (incl. migration runbooks)
65+
├── .machine_readable/ # Canonical SCM metadata
66+
├── .github/ .well-known/ LICENSES/ # Governance, protocols, licenses
67+
└── flake.nix / Justfile / stapeln.toml / opsm.toml # Shared env & orchestration
6868
```
6969

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

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

7581
## SESSION STARTUP CHECKLIST
7682

‎AGENTS.md‎

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

‎CLAUDE.md‎

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

‎CONTRIBUTING.md‎

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

0 commit comments

Comments
 (0)